Hybris UX Api

POST

This operation creates a shippingOrder entity.

In order to create an order in the system you will need to first create a delivery intent (/searchTimeSlot) and then create an order with the delivery intent. This ensures that the API consumers received availability schedule along with the delivery intent created. The Front end must display the delivery schedule to the user for selection. Once the user selects the schedule the calling system must sent us the time selected along with the delivery intent id and order information.

Create Delivery Intent(/searchTimeSlot) is the first API the partner must request in order to get the latest schedule of the business. The schedule will display only the next two weeks from today. If we do not have a delivery available for that day the system will not display a schedule for that day.

The delivery intent window is 15 minutes from creation. If more than 15 minutes have passed from the delivery intent creation, the order creation will return an error.

Address, latitude and Longitude should be matching for the Delivery.

If slot for Delivery is not available, then Shipping Order cannot be created for Delivery. API Response contains deliverytime (which is converted to simplified extended ISO format (ISO 8601)) which is different from the request.

URL

https://[localhost]:[port]/ecom-ux/v1/{businessId}/shippingOrder

URL PARAMS

Header

Request

{
    "note": [
        {
            "text": "Alias in voluptatum et facilis."
        }
    ],
    "placeTo": {
        "id": "00605",
        "@baseType": "Place",
        "@referredType": "GeographicAddress",
        "name": "65535 Eriberto Via",
        "role": "DeliveryAddress"
    },
    "relatedParty": [
        {
            "name": "John Doe",
            "role": "Recepient",
            "@referredType": "Individual",
            "contactMedium": [
                {
                    "mediumType": "Phone",
                    "characteristic": {
                        "phoneNumber": "650-219-7083"
                    }
                },
                {
                    "mediumType": "Email",
                    "characteristic": {
                        "email": "Jarret.Kling47@yahoo.com"
                    }
                }
            ]
        },
        {
            "name": "Karlee",
            "role": "RecipientAdditionalContact",
            "@referredType": "Individual",
            "contactMedium": [
                {
                    "mediumType": "Phone",
                    "characteristic": {
                        "phoneNumber": "276-455-8663"
                    }
                }
            ]
        }
    ],
    "shippingOrderCharacteristic": [
        {
            "name": "segment",
            "value": "Comercial"
        },
        {
            "name": "clientLatitude",
            "value": "21.5354"
        },
        {
            "name": "clientLongitude",
            "value": "139.6653"
        },
        {
            "name": "serviceType",
            "value": "tienda_a_cliente"
        },
        {
            "name": "operationArea",
            "value": "ecommerce"
        },
        {
            "name": "budgetCampaignTags",
            "value": "ecommerceCampaign"
        }
    ],
    "shippingOrderItem": [
        {
            "id": "01",
            "action": "add",
            "shipment": {
                "id": "1793",
                "requestedDeliveryDate": "2022-10-19T09:30:00.000Z",
                "externalIdentifier": [
                    {
                        "id": "6887b9cd-bd93-4f4a-a323-831060d2887d",
                        "owner": "ecommerce"
                    }
                ]
            }
        }
    ],
    "productOrder": {
        "id": "21322617"
    },
    "billingAccount": {
        "id": "9188364",
        "@type": "billingAccount"
    }
}

Response

{
    "id": "5fe93a14-7420-4ff9-852e-7668afad2cc1",
    "status": "RECEIVED",
    "note": [
        {
            "text": "Alias in voluptatum et facilis."
        }
    ],
    "placeTo": {
        "id": "00605",
        "@baseType": "Place",
        "@referredType": "GeographicAddress",
        "name": "279 AVE PONCE DE LEON",
        "role": "DeliveryAddress"
    },
    "relatedParty": [
        {
            "name": "DevTest Lokesh",
            "role": "Recepient",
            "@referredType": "Individual",
            "contactMedium": [
                {
                    "mediumType": "Phone",
                    "characteristic": {
                        "phoneNumber": "+19059334010"
                    }
                },
                {
                    "mediumType": "Email",
                    "characteristic": {
                        "email": "LokeshMahidhar@gmail.com"
                    }
                }
            ]
        },
        {
            "name": "DevTest Lokesh",
            "role": "RecipientAdditionalContact",
            "@referredType": "Individual",
            "contactMedium": [
                {
                    "mediumType": "Phone",
                    "characteristic": {
                        "phoneNumber": "+16502198888"
                    }
                }
            ]
        }
    ],
    "shippingOrderCharacteristic": [
        {
            "name": "segment",
            "value": "Comercial"
        },
        {
            "name": "clientLatitude",
            "value": "18.4242052"
        },
        {
            "name": "clientLongitude",
            "value": "-66.0593442"
        },
        {
            "name": "serviceType",
            "value": "tienda_a_cliente"
        },
        {
            "name": "operationArea",
            "value": "ecommerce"
        },
        {
            "name": "budgetCampaignTags",
            "value": "ecommerceCampaign"
        },
        {
            "name": "phoneCarrier",
            "value": ""
        },
        {
            "name": "businessParkingInformation",
            "value": "La tienda esta dentro del shopping"
        },
        {
            "name": "pickupTaskUrl",
            "value": "https://jngl.ml/LR42a10c9"
        },
        {
            "name": "deliveryTaskUrl",
            "value": "https://jngl.ml/0aQ01N27b"
        },
        {
            "name": "trackingLink",
            "value": ""
        }
    ],
    "shippingOrderItem": [
        {
            "id": "28331",
            "action": "add",
            "shipment": {
                "id": "3683",
                "state": "RECEIVED",
                "requestedDeliveryDate": "2023-02-06T13:00:00.000Z",
                "externalIdentifier": [
                    {
                        "id": "6887b9cd-bd93-4f4a-a323-831060d2887d",
                        "owner": "ecommerce"
                    }
                ]
            }
        }
    ],
    "productOrder": {
        "id": "1200047892881019"
    },
    "billingAccount": {
        "id": "8211990010051001",
        "@type": "billingAccount"
    }
}

Possible response error

In this section all the possible data structures received by the client are defined and that must be considered as unsatisfactory when responding to the method.

[ 400 ]

Bad Request - Delivery Intent window is 15 minutes. Repeat /searchTimeSlot call and capture new Delivery Intent Id. The client SHOULD repeat the request with new ID.

{
  "errors" : [{
      "code" : 400,
      "message" : "Invalid Delivery Intent: 3243",
      "description" : "Delivery Intent window has expired. Create new delivery intent and try again."
    }]
}

GET

This operation List/Finds shippingOrder entities based on the request.

URL

https://[localhost]:[port]/ecom-ux/v1/{businessId}/shippingOrder

URL PARAMS

Header

QUERY PARAMS

Note: one query parameter should be present in each request and not more than one.

RESPONSE

Each of the additional characteristics are detailed.

[
    {
        "id": "2656b75f-cf18-4e47-b1b2-7f23077b389e",
        "status": "RECEIVED",
        "note": [
            {
                "text": "Alias in voluptatum et facilis."
            }
        ],
        "placeTo": {
            "id": "00604",
            "@baseType": "Place",
            "@referredType": "GeographicAddress",
            "name": "65535 Eriberto Via",
            "role": "Recipient"
        },
        "relatedParty": [
            {
                "name": "Cap Test 1",
                "role": "Recepient",
                "@referredType": "Individual",
                "contactMedium": [
                    {
                        "mediumType": "Phone",
                        "characteristic": {
                            "phoneNumber": "+16502197083"
                        }
                    },
                    {
                        "mediumType": "Email",
                        "characteristic": {
                            "email": "capgTest@gmail.com"
                        }
                    }
                ]
            },
            {
                "name": "Karlee",
                "role": "Recepient",
                "@referredType": "Individual",
                "contactMedium": [
                    {
                        "mediumType": "Phone",
                        "characteristic": {
                            "phoneNumber": "+12764558663"
                        }
                    }
                ]
            }
        ],
        "shippingOrderCharacteristic": [
            {
                "name": "segment",
                "value": "Comercial"
            },
            {
                "name": "clientLatitude",
                "value": "21.5354"
            },
            {
                "name": "clientLongitude",
                "value": "139.6653"
            },
            {
                "name": "serviceType",
                "value": "tienda_a_cliente"
            },
            {
                "name": "operationArea",
                "value": "ecommerce"
            },
            {
                "name": "budgetCampaignTags",
                "value": "ecommerceCampaign"
            },
            {
                "name": "phoneCarrier",
                "value": "AT&T Wireless"
            },
            {
                "name": "businessParkingInformation",
                "value": "La tienda esta dentro del shopping"
            },
            {
                "name": "trackingLink",
                "value": ""
            }
        ],
        "shippingOrderItem": [
            {
                "id": "27604",
                "action": "add",
                "shipment": {
                    "state": "RECEIVED",
                    "requestedDeliveryDate": "2022-11-05T16:30:00.000Z",
                    "externalIdentifier": [
                        {
                            "id": "6887b9cd-bd93-4f4a-a323-831060d2887d",
                            "owner": "ecommerce"
                        }
                    ]
                }
            }
        ],
        "productOrder": {
            "id": "21321122"
        },
        "billingAccount": {
            "id": "9181122",
            "@type": "billingAccount"
        }
    }
]

PATCH

This operation updates a shippingOrder entity. In order to Update an order in the system you will need to use uuid from the response of create order. Update delivery instructions, Cancellation of order by updating status and Update delivery address are in scope for Patch /shippingOrder.

If a customer wants to change the delivery time of an order the system needs to cancel the current order and create a new order (new delivery intent and new order placement) with the updated information.

For cancellation status value should be "CANCELLED" as per request example.

Following Information that cannot be updated:

1. Delivery Time (requestedDeliveryDate)
2. Delivery Intent (shipment.id)

This fields cannot be updated because it would alter the delivery intent. If a customer wants to change the delivery time of an order the system needs to cancel the current order and create a new order (new delivery intent and new order placement) with the updated information.

URL

https://[localhost]:[port]/ecom-ux/v1/{businessId}/shippingOrder/{id}

URL PARAMS

Header

Request

Note: Values will be updated if it is present in the request with non Empty/null values

Update delivery instructions:

{
    "note": [
        {
            "text": "Alias in voluptatum et facilis."
        }
    ]
}

Cancel Delivery Order by updating status:

{
    "status": "CANCELLED",
        "note": [
        {
            "text": "Alias in voluptatum et facilis."
        }
    ],
    "relatedParty": [
        {
            "name": "Karlee",
            "role": "Recepient",
            "@referredType": "Individual"
        }
    ],
    "shippingOrderCharacteristic": [
        {
            "name": "operationArea",
            "value": "ecommerce"
        },
        {
            "name": "cancelMessage",
            "value": "Client not interested"
        }
    ]
}

Update Delivery Address:

{
    "placeTo": {
        "id": "00604",
        "@baseType": "Place",
        "@referredType": "GeographicAddress",
        "name": "65535 Eriberto Via",
        "role": "DeliveryAddress"
    },
    "shippingOrderCharacteristic": [
        {
            "name": "clientLatitude",
            "value": "21.5354"
        },
        {
            "name": "clientLongitude",
            "value": "139.6653"
        }
    ]
}

Response

{
    "id": "25c94f58-19f4-44db-8f34-154b6f52a3b8",
    "status": "CANCELED BY LIB REP",
    "note": [
        {
            "text": "Alias in voluptatum et facilis."
        }
    ],
    "placeTo": {
        "id": "00605",
        "href": "https://host/tmf-api/geographicAddressManagement/v4/geographicAddress/00605",
        "@baseType": "Place",
        "@referredType": "GeographicAddress",
        "name": "65535 Eriberto Via",
        "role": "DeliveryAddress"
    },
    "relatedParty": [
        {
            "name": "John Doe",
            "role": "Recepient",
            "@referredType": "Individual",
            "contactMedium": [
                {
                    "mediumType": "Phone",
                    "characteristic": {
                        "phoneNumber": "6502197083"
                    }
                },
                {
                    "mediumType": "Email",
                    "characteristic": {
                        "email": "Jarret.Kling47@yahoo.com"
                    }
                }
            ]
        },
        {
            "name": "Karlee",
            "role": "RecipientAdditionalContact",
            "@referredType": "Individual",
            "contactMedium": [
                {
                    "mediumType": "Phone",
                    "characteristic": {
                        "phoneNumber": "6502197084"
                    }
                }
            ]
        }
    ],
    "shippingOrderCharacteristic": [
        {
            "name": "segment",
            "value": "Comercial"
        },
        {
            "name": "clientLatitude",
            "value": "21.5354"
        },
        {
            "name": "clientLongitude",
            "value": "139.6653"
        },
        {
            "name": "serviceType",
            "value": "tienda_a_cliente"
        },
        {
            "name": "operationArea",
            "value": "ecommerce"
        },
        {
            "name": "budgetCampaignTags",
            "value": "ecommerceCampaign"
        },
        {
            "name": "phoneCarrier",
            "value": "AT&T Wireless"
        },
        {
            "name": "businessParkingInformation",
            "value": "La tienda esta dentro del shopping"
        },
        {
            "name": "trackingUrl",
            "value": "https://jngl.ml/Udda3E03b"
        }
    ],
    "shippingOrderItem": [
        {
            "id": "34323",
            "action": "modify",
            "shipment": {
                "state": "CANCELED BY LIB REP",
                "requestedDeliveryDate":"2022-10-21T10:30:00.000Z",
                "externalIdentifier": [
                    {
                        "id": "6887b9cd-bd93-4f4a-a323-831060d2887d",
                        "owner": "ecommerce"
                    }
                ]
            }
        }
    ],
    "productOrder": {
        "id": "21321122"
    },
    "billingAccount": {
        "id": "9188364",
        "href": "https://host/tmf-api/accountManagement/v4/billingAccount/9188364"
    }
}

Possible response error

In this section all the possible data structures received by the client are defined and that must be considered as unsatisfactory when responding to the method.

[ 400 ]

Bad Request - the request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

{
  "errors" : [{
      "code" : 400,
      "message" : "Required key not found",
      "description" : "No value provided for the cancelation message. Please provide a cancelation reason."
    }]
}